A.C.E. 1

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 1 / ACE CD 1.iso / files / docs / blitzbad.lha / BlitzBasic2V1.3Part1.doc < prev next >

Wrap

Text File | 1994-12-14 | 111.2 KB | 3,444 lines

BLITZ BASIC 2 LIBRARY GUIDE V1.3 Last updated on: 16-10-1994 written by Jurgen Valks mail me for futher updates: j.valks@sbos.nl NOW INCLUDING THE BUM MAGAZINE COMMANDS!!: Thanks Simon! Make a choice ALL PD/UPDATE COMMANDS SEE ALL THE PD LIBRARIES INCLUDED BUM MAGAZINES 1-6 / COMMANDS BUM 7 INFO This file contains all the commands of the following libraries: CIA-TRACKER LIBRARY COMMODITIES LIBRARY ELMORE LIBRARY FX LIBRARY FNS LIBRARY FUNC LIBRARY GFX LIBRARY PACK LIBRARY PCF LIBRARY REQ LIBRARY RIANIM LIBRARY TOOLTYPES LIBRARY TRACKDISK LIBRARY WB LIBRARY ZONE-JOY LIBRARY ============================================ = T R A C K D I S K L I B R A R Y = ============================================ (C)1994 Reflective Images Written by Steve Matty. You can do whatever the hell you like to this library but must still give me some credit! Command List : CLOSEDISK MOTORON MOTOROFF =FORMATTRACK =OPENDISK =READSECTOR =WRITESECTOR =WRITEBOOT Command : OpenDisk -------------------------------------------------------------------------- Modes : Amiga Syntax : success=OpenDisk(unit#) This attempts to open unit 'unit#' of the trackdisk.device, for use with the other commands in this library. A return value of 0 indicates failure, -1 indicates success. Statement : MotorOn -------------------------------------------------------------------------- Modes : Amiga Syntax : MotorOn unit# This attempts to switch the drive motor on of the previously opened trackdisk unit (called with OpenDisk). You must call this command before attempting to ReadSector/WriteSector/FormatTrack/WriteBoot Statement : MotorOff -------------------------------------------------------------------------- Modes : Amiga Syntax : MotorOff unit# This turns the drive motor of 'unit#' off. Command : ReadSector -------------------------------------------------------------------------- Modes : Amiga Syntax : [success=]ReadSector(unit#,sector#,buffer[,numsectors]) This attempts to read 'numsectors' sectors from a trackdisk device which has been opened with OpenDisk and has its Motor On. If numsectors is omitted then 1 sector is read. The data is read into the memory location pointed to by 'buffer'. WARNING! Please MAKE SURE the MOTOR is _ON_ otherwise, all hell will break loose!!! Command : WriteSector -------------------------------------------------------------------------- Modes : Amiga Syntax : [success=]WriteSector(unit#,sector#,buffer[,numsectors]) This is the same as ReadSector except........... it writes! (and no, I am not being lazy by not typing any decent docs) Command : FormatTrack -------------------------------------------------------------------------- Modes : Amiga Syntax : [success=]FormatTrack(unit#,track#,buffer[,numtracks]) This does a TD_FORMAT on the specified track number. Buffer should point to the area of memory which the track should be formatted with. I don't know why this command exists - but hey, it might come in useful. Statement : CloseDisk -------------------------------------------------------------------------- Modes : Amiga Syntax : CloseDisk unit# This closes the trackdisk.device of the specified unit#. The Motor is automatically switched off if it is already on. Command : WriteBoot -------------------------------------------------------------------------- Modes : Amiga Syntax : [success=]WriteBoot(unit#[,buffer]) This writes 1kilobyte of data to the bootblock of the specified disk unit. The optional buffer parameter should point to an area of memory with which to write the bootblock. RIAnim Library v1.0 =================== By Stephen McNamara (c)1994 Reflective Images RIANIM COMMANDS This library enables the playback of both Anim5 and Anim7 format animations. It allows you to playback animations at any co-ordinate in a bitmap and supports different palettes for frames of the animation. It also allows you to playback animations from FAST ram, thus you can now play massive animations that can only fit in FAST ram. When playing back animations you must make sure that your display is double-buffered. Please refer to the Blitz manual for information about how anims can be played back properly - or look at the example program included with this file. Note: there may still be a few bugs in the animation playback routines - if you have any problems or spot any bugs then please contact us at the address given in the main file of this archive. These are the RIANIM library commands: ANIMLOOP RIANIMINIT RINEXTANIMFRAME =RIANIMINIT =RINEXTANIMFRAME Statement/Function: RIAnimInit -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: [suc=]RIAnimInit(address,bitmap#,palette#[,xy_offset]) This command attempts to take an animation held in memory (CHIP or FAST) and identify it as a supported animation format. If it identifies it okay it will set up the animation by unpacking frame 1 of the anim onto the specified bitmap and copying the palette to the specified palette object. You must ensure that the bitmap is big and deep enough to actually hold the animation. At the moment there is no checking of the bitmap size. The palette object you give is automatically resized to the size of the palette in the animation. The optional parameter allows you to play an animation at an offset into a bitmap. Thus you could center a half screen animation on a bitmap. The offset is given as a byte offset from the start of each bitplane. It is calculated like this: offset=(X/8)+(Y*(pixel_width/8)) where: X and Y are your co-ordinates pixel_width is the width of your bitmap. If used as a function, this command returns true for a successful initialise or false for failure. Statement/Function: RINextAnimFrame ------------------------------------------------------------------------ Modes : Amiga/Blitz Syntax: [suc=]RINextAnimFrame bitmap# This command attempts to unpack the next frame of a previously initialised animation onto the specified bitmap. It returns true or false to say whether it succeeded or not. Statement: AnimLoop ------------------------------------------------------------------------ Modes : Amiga/Blitz Syntax: AnimLoop ON|OFF This command allows you to control the looping mode of the animation. With animloop off, playback of an animation will stop at the last frame of it. Any attempt to draw another frame will fail. With it on, though, the animation will loop around. Note: you must ensure that your animation has loop frames at the end of it if you want to loop the animation around. The reverse of this is true for animloop off - the animation must not have loop frames if you don't want it to loop around. If you select animloop off but have looping frames in your anim then the animation will end by displaying a copy of frame 2 of the animation. -------------------------------------------------------------------------- ==== Reflective Images Commodities Library V0.9 (C)1994 ==== -------------------------------------------------------------------------- COMMODITIES COMMANDS Introduction ============ This library allows the easy use of Commodities. It requires Kickstart 2 or higher. The COMMODITIES library commands: EXCHANGEAPPEAR EXCHANGEDISAPPEAR EXCHANGEENABLE EXCHANGEDISABLE EXCHANGEKILL EXCHANGECHANGELIST EXCHANGEUNIQUE MAKECOMMODITY SETSTATUS SETHOTKEY =HOTKEYHIT =COMMODITYEVENT =EXCHANGEMESSAGE =CXAPPEAR =CXDISAPPEAR =CXENABLE =CXDISABLE =CXKILL =CXCHANGELIST =CXUNIQUE Function : MakeCommodity -------------------------------------------------------------------------- Modes : Amiga Syntax : success=MakeCommodity(name$,title$,description$) This command attempts to add your Commodity to the list of commodities. A return value of -1 indicates success, 0 means failure. (not enough memory) name$ refers to the name of the Commodity and it should be unique. This is the name that appears when running the Commodity Exchange program. title$ is the title of your program, e.g. "My Screen Blanker". description$ is a brief description of your program. The Commodity Exchange program will then have 'name$' in its list of Commodities and when a user clicks on your commodity, it will display the title$ and description$. Function : SetHotKey -------------------------------------------------------------------------- Modes : Amiga Syntax : success=SetHotKey(hotkey#,hotkeydescription$) This will add a hotkey event to your commodity so that after a hotkey has been pressed you can find out which one. e.g. success=SetHotKey(0,"lalt lshift a") Function : HotKeyHit -------------------------------------------------------------------------- Modes : Amiga Syntax : hitkeynum=HotKeyHit This will return the number of the hot key which has been hit since the last 'CommodityEvent' was called, or -1 if no such hotkey has been activated. Function : CommodityEvent -------------------------------------------------------------------------- Modes : Amiga Syntax : anyevent=CommodityEvent This looks to see if either a) A hotkey has been pressed b) A message from Exchange has been received and returns -1 if such an event occurred, of 0 is nothing has yet happened. This should be inside a Repeat-Until loop, e.g. Repeat VWait ev.l=Event ce.l=CommodityEvent hk.l=HotKeyHit ; This must be used after Until ev or ce or hk ; CommodityEvent Statement : SetStatus -------------------------------------------------------------------------- Modes : Amiga Syntax : SetStatus on|off This sets the status of your Commodity to either Active (on) or Inactive (off) - this can be seen by running the Commodities Exchange program. Function : ExchangeMessage -------------------------------------------------------------------------- Modes : Amiga Syntax : messnum.l=ExchangeMessage This looks to see if the Commodities Exchange has issued you with as message, e.g. Hide Interface, Show Interface. It returns the message ID of the incoming message or 0 for no message. Functions: CxAppear/CxDisAppear/CxEnable/CxDisable CxKill/CxChangeList/CxUnique -------------------------------------------------------------------------- Modes : Amiga These are to be used in conjunction with ExchangeMessage, ie em.l=ExchangeMessage Select em Case CxAppear Gosub _appear Case CxDisAppear Gosub _disappear End Select The functions merely return the ID value associated with that particular Commodities Exchange message. Functions: ExchangeAppear/ExchangeDisAppear/ExchangeEnable/ ExchangeDisable/ExchangeKill/ExchangeChangeList/ExchangeUnique -------------------------------------------------------------------------- Modes : Amiga To be used in conjunction with ExchangeMessage, ie em.l=ExchangeMessage If em If ExchangeAppear then Gosub _appear If ExchangeDisAppear then Gosub _dispappear EndIf This is intended as an alternative way of acting upon Exchange Messages. ;------------------------------ ;- WB library version 0.9 - ;- ©1994 Reflective Images - ;------------------------------ WB COMMANDS This small library provides quick and easy to use commands for accessing AppWindows, AppIcons and AppMenus. * PLEASE NOTE * This library must have at least V37+ of Workbench/DOS/Icon libraries This version of the library only enables you to read the FIRST file dragged to an AppWindow/AppIcon or selected from an AppMenu - future versions will have additional commands AppWindowArg/AppIconArg/ AppMenuArg which returns the filename of the specified arg. E.g. f$=AppIconArg(1) The WB commands: APPEVENT APPWINDOWEVENT APPICONEVENT APPMENUEVENT ADDAPPWINDOW ADDAPPICON ADDAPPMENU DELAPPWINDOW DELAPPICON DELAPPMENU APPWINDOWFILE APPICONFILE APPICONHIT APPMENUFILE APPMENUHIT Function : AppEvent -------------------------------------------------------------------------- Modes : Amiga Syntax : status=AppEvent This command checks the msg ports of any open AppIcons/AppWindows/ AppMenus and if an event has been passed, returns -1. 0 indicates no event has occurred. e.g. Repeat VWait Until AppEvent Function : AppWindowEvent -------------------------------------------------------------------------- Modes : Amiga Syntax : status=AppWindowEvent This command checks the msg ports of any open AppWindows and if an event has been passed, returns -1. 0 indicates no event has occurred. e.g. Repeat VWait Until AppWindowEvent Function : AppIconEvent -------------------------------------------------------------------------- Modes : Amiga Syntax : status=AppIconEvent This command checks the msg ports of any AppIcons and if an event has been passed, returns -1. 0 indicates no event has occurred. e.g. Repeat VWait Until AppIconEvent Function : AppMenuEvent -------------------------------------------------------------------------- Modes : Amiga Syntax : status=AppMenuEvent This command checks the msg ports of any AppMenus and if an event has been passed, returns -1. 0 indicates no event has occurred. e.g. Repeat VWait Until AppMenuEvent Function : AddAppWindow -------------------------------------------------------------------------- Modes : Amiga Syntax : success=AddAppWindow(windownumber) This command attempts to make the window specified by 'windownumber' to become an AppWindow. -1 means success, 0 means failure. There is a currently limit of 4 AppWindows. Function : AddAppIcon -------------------------------------------------------------------------- Modes : Amiga Syntax : success=AddAppIcon(id,text$,iconname$) This command attempts to place an AppIcon onto the Workbench desktop. ID is a unique identification number. Text$ is text to display underneath the AppIcon and Iconname$ is the name of the file to use the Icon imagery. -1 means success, 0 means failure. e.g. suc=AddAppIcon(0,"Test","Work:Test") If suc=0 Then End Function : AddAppMenu -------------------------------------------------------------------------- Modes : Amiga Syntax : success=AddAppMenu(id,text$) This command tries to add 'text$' to the Tools menu of Workbench. ID is a unique identification number. Returns -1 for success, 0 for failure. e.g. suc=AddAppMenu(0,"Blitz2") If suc=0 Then End Function : AppWindowFile -------------------------------------------------------------------------- Modes : Amiga Syntax : filename$=AppWindowFile(windownumber) This command returns the complete path of the file which was dragged to the AppWindow. If the file was in fact a directory a '/' is appended. An empty string signifies nothing was Dragged. Function : AppIconFile -------------------------------------------------------------------------- Modes : Amiga Syntax : filename$=AppIconFile(id) This command returns the complete path of the file which was dragged to the AppIcon. If the file was in fact a directory a '/' is appended. An empty string signifies nothing was Dragged. Function : AppMenuFile -------------------------------------------------------------------------- Modes : Amiga Syntax : filename$=AppMenuFile(id) This command returns the complete path of the file which was selected when the AppMenu was hit. If the file was in fact a directory a '/' is appended. An empty string signifies nothing was selected. Function : AppIconHit -------------------------------------------------------------------------- Modes : Amiga Syntax : status=AppIconHit(id) idnumber=AppIconHit This command returns the status of the AppIcon <id>. -1 = The icon was doubleclicked, 0 = nothing has happened. If no argument is supplied, the function returns the number of the doubleclicked icon, or -1 for none. Function : AppMenuHit -------------------------------------------------------------------------- Modes : Amiga Syntax : status=AppMenuHit(id) idnumber=AppMenuHit This returns the status of the AppMenu item <id>. -1 = This menu item was selected, 0 = This menu item was not selected. If no argument is given, the function returns the numbe of the selected menu item, or -1 for none. Function : DelAppWindow/DelAppIcon/DelAppMenu -------------------------------------------------------------------------- Modes : Amiga Syntax : success=DelAppWindow[(number)] success=DelAppIcon[(id)] success=DelAppMenu[(id)] These commands will remove the AppWindow/AppIcon/AppMenu from the system and free up the associated message ports. *** IMPORTANT *** You must call DelAppWindow BEFORE closing a window, or your machine will GURU! Reflective Images Tooltypes Library =================================== Release #2 TOOLTYPES COMMANDS By Stephen McNamara, inspired by the collection of tooltype functions by Mark Tiffany. (c)1994 Reflective Images This library contains commands to allow the reading, comparing and setting of tooltypes in a .info file. All tooltype names are case insignificant but as a general sort of rule they should really be completely uppercase. This library attempts to open the system Icon.library, if the opening of this library fails ALL commands in this library will be unusable. Almost every function in this library relies on the Icon.library completely. Changed commands: FindToolValue - now returns "" if the tooltype was found but did not have a value (e.g. DONOTWAIT). You should now use FindToolType to check for the existance of a tooltype and then use FindToolValue to get its value. PutIconObject - now has an optional parameter that lets you set the type of the file. See SetIconType for more information about possible values for this command. Command list: GETICONOBJECT PUTICONOBJECT FREEICONOBJECT FINDTOOLVALUE FINDTOOLNUMBER ICONDEFAULTTOOL ICONRENDER MATCHTOOLVALUE SETICONHIT SETICONTYPE SETTOOLVALUE SHAPETOICON NEWTOOLTYPE CLEARTOOLTYPES =FINDTOOLTYPE Statement: SetIconHit -------------------------------------------------------------------------- Modes : Amiga Syntax : SetIconHit width#,height# This command sets the size of the 'hit-box' around the image in the currently loaded .info file. This is only of use if your info file has an image associated with it. You should note that the hit box should never be smaller, horizontally or vertically, than the actual size of the image. When Workbench renders an image for a file onto a window, it automatically puts a 3d box border around it. The size of the hit box determines the size of this border. Your image will always be located in the top left border of the hit box. Statement: ShapeToIcon -------------------------------------------------------------------------- Modes : Amiga Syntax : ShapeToIcon shape#[,shape#] This command lets you change the images associated with the currently loaded .info file. What it does is to set up the .info file in memory so that when it is saved out next, the images you give are saved out with it. Using this command does not actually copy any shape data around memory, all it does it place a pointer in the .info to the shape data. You should therefore not delete a shape WITHOUT first saving the .info file to disk (that is of course if you want to keep your changes). When you use this command, the hit box area for the .info file is automatically set to the size of the first shape given. It is important, therefore, that the second shape is not larger than the first. When you give a second shape, this shape is set up to be the 'alternate render' image, this means that this is the second image associated with the .info file (remember the two windows in the IconEditor?) Statement: SetIconType -------------------------------------------------------------------------- Modes : Amiga Syntax : SetIconType type# This command lets you specify the type of the file associated with the currently loaded .info file. The type describes whether or not the file is a tool or project etc...., and can take the following values: 1 Disk 2 Drawer 3 Tool 4 Project 5 Trashcan This command is identical to the menu in the IconEditor 'Type'. Statement: IconRender -------------------------------------------------------------------------- Modes : Amiga Syntax : IconRender mode# This command lets you specify what Workbench should do to the icons image when the user clicks on it. It lets you choose whether a separate image should be displayed or whether the current image should just be modified. Mode# is made up of several different values that should be added together to create different effects, these are: 0 Complement the select box 1 Draw a box around the image 2 Draw the alternate image 3 Don't highlight 4 Double image icon Thus if you wanted an icon to change to a second image when selected, and the icon has a second image, you would set the render to 6 (4+2). This would mean that you had a second image (4) and that you wanted it to be displayed when you select the icon (2). Note: when you use ShapeToIcon with two shape numbers the IconRender is automatically set to 6. Statement: IconDefaultTool -------------------------------------------------------------------------- Modes : Amiga Syntax : IconDefaultTool tool$ This command lets you set the default tool for the current .info file. The default tool only applies for project files (see SetIconType) and is the program that is run when you double click the icon file (e.g. all Blitz2 source code files saved out with icons have the default tool 'Blitz2:Blitz2'). This command can be used to make a file saved out by your program double-clickable. I have used it myself to make map files saved out from my editor automatically load the editor when selected. Statement: FindToolType -------------------------------------------------------------------------- Modes : Amiga Syntax : bool=FindToolType (tool$) This command simply returns true or false to say whether or not the given tooltype was found in the currently loaded .info file. Statement/Function: GetIconObject ------------------------------------------------------------------------ Modes : Amiga Syntax : GetIconObject filename$ suc.l=GetIconObject (filename$) This command reads in a .info file from disk. The filename given will have '.info' added to the end of it and will be loaded into memory (chip or fast depending on what is available for allocation) as a diskobject. Please refer to the Amiga hardware includes for information about the diskobject structure (or see your Blitz Basic Amigalibs resident file). If used as a function, this command will return either FALSE for failure or the address of the allocated diskobject in memory. Statement/Function: PutIconObject ------------------------------------------------------------------------ Modes : Amiga Syntax : PutIconObject filename$ suc.l=PutIconObject (filename$) This command takes a diskobject structure reserved and initialised by GetIconObject and saves it out to disk as a .info file for the specified file. All current tooltypes and values will be saved with the file. The optional parameter allows you to set the type of the file associated with the .info file. See SetIconType for possible values for this parameter. Note that if you leave out this parameter the icontype will not be changed. Statement/Function: FreeIconObject ------------------------------------------------------------------------ Modes : Amiga Syntax : FreeIconObject suc.l=FreeIconObject This command will free up the diskobject that is currently being used. It will not save out any tooltype changes and will free up the memory without ANY changes being made to the .info file loaded from disk. Function: FindToolValue ------------------------------------------------------------------------ Modes : Amiga Syntax : toolval$=FindToolValue(tooltype$) This function returns the value of the selected tooltype. The return value is a string, and is the part of the tooltype string after the "=" in the tooltype entry. The tooltype$ string that you pass can be in either lower case or uppercase since all testing in done in uppercase, although as a general rule, all tooltypes should be in uppercase. This function will return a null string if the named tooltype was not found in the list of tooltypes for the file. If the selected tooltype did not have an actual value (e.g. DONOTWAIT) then this function will return the string "!!". Function: FindToolNumber ------------------------------------------------------------------------ Modes : Amiga Syntax : toolval$=FindToolNumber(tooltype$) This command will return the FULL tooltype string in the selected tooltype position. If the tooltype number does not exist then "" will be returned. Example: tooltypes: "DONOTWAIT" "CLOCKX=157" FindToolNumber(0) will return "DONOTWAIT" FindToolNumber(1) will return "CLOCKX" FindToolNumber(49) will return "" Function: MatchToolValue ------------------------------------------------------------------------ Modes : Amiga Syntax : suc.l=MatchToolValue(tooltype$,value$) This command searchs the current list of tooltypes for the selected tooltype and, if found, attempts to match the values of it with the given value. This command uses the operating system call MatchToolType(), it is able to cope with a tool having more than one value, e.g. LANGUAGE=ENGLISH|FRENCH (the | is used to show OR, thus this tooltype means that LANGUAGE equals ENGLISH or FRECH) When using match toolvalue with this tooltype, TRUE will be returned when you use value$="ENGLISH" or "FRENCH" but not (I think) both. You should note that for this command, the case of VALUE$ is insignificant. Statement/Function: SetToolValue ------------------------------------------------------------------------ Modes : Amiga Syntax : SetToolValue tooltype$,value$ suc.l=SetToolValue (tooltype$,value$) This command will attempt to set a tooltype that is currently defined to the specified value. When used as a function, this command will return TRUE for success or FALSE for failure, possible failures include: no icon file loaded and tooltype not found. When used, this command attempts to allocate memory to store the new tooltype information in, it does not attempt to free up the old memory allocated to the tooltype. This means that you should keep alterations of tooltypes to a minimum. The best way to manage tooltypes is: 1. Open the icon 2. Read the tooltypes 3. Close the icon 4. ... do your program ... 5. Open the icon 6. Alter the tooltypes 7. Save the icon Using this series of events, you'll keep memory usage (which will be fairly small anyway...) to the very minimum. Statement/Function: NewToolType ------------------------------------------------------------------------ Modes : Amiga Syntax : NewToolType tooltype$,value$ suc.l=NewToolType (tooltype$,value$) This command allocates a new tooltype in the currently loaded .info file and sets its value. No check is done to see is the tooltype already exists and the new tooltype is added to the end of the current list of tooltypes. Statement: ClearToolTypes ------------------------------------------------------------------------ Modes : Amiga Syntax : ClearToolTypes This command is used to clear all the tooltype information from the currently loaded .info file. It does not attempt, though, to free up all the memory reserved to store tooltype names and values, you should therefore not used this command too many times in a row. Once you have used this command, any attempt to read tooltype values will fail. ;------------------------------ ;- ReqLib.library version 0.9 - ;- ©1994 Reflective Images - ;------------------------------ REQ COMMANDS The well known Req.Library for the Amiga is one of the best file requesters around, so I wrote this small lib to enable Blitz users to have Req requesters in their programs with the minimum of hassle. * PLEASE NOTE * That this library must have at least v2.2 of the Req.Library available. Command List: REQOUTPUT REQFILEREQUEST REQFILELOC REQ FLAGS, STRUCTURE Statement: ReqOutput -------------------------------------------------------------------------- Modes : Amiga Syntax : ReqOutput windownumber This command sets the ReqLib.library to put all requesters onto the window specified by <windownumber>. If this command is not called then the requesters will appear on the Default Public Screen. Function: ReqFileRequest -------------------------------------------------------------------------- Modes : Amiga Syntax : pathname$=ReqFileRequest([title$[,flags]]) This opens up the standard file requester. If <title$> is given then the text will appear on the requester title bar. The optional <flags> parameter specifies a flag setting (see below) for use. If this is omitted then the last flag setting is used. Function: ReqFileLoc ------------------------------------------------------------------ Modes : Amiga/Blitz Syntax : memorylocation.l=ReqFileLoc This simply returns the address in memory where the Req.Library file requester stucture is located. FLAGS ===== Below is a list of possible flag settings and a brief description of each. #FRQSHOWINFOB = %1 ;Set to show .info files. Default is not. #FRQEXTSELECTB = %10 ;Extended select. Default is not. #FRQCACHINGB = %100 ;Directory caching. Default is not. #FRQGETFONTSB = %1000 ;Font requester rather than a file requester. #FRQINFOGADGETB = %10000 ;Hide-info files gadget. #FRQHIDEWILDSB = %100000 ;DON'T want 'show' and 'hide' string gadgets. #FRQABSOLUTEXYB = %1000000 ;Use absolute x,y positions rather than centering on mouse. #FRQCACHEPURGEB = %10000000 ;Purge the cache whenever the directory date stamp changes if this is set. #FRQNOHALFCACHEB = %100000000 ;Don't cache a directory unless it is completely read in when this is set. #FRQNOSORTB = %1000000000 ;DON'T want sorted directories. #FRQNODRAGB = %10000000000 ;DON'T want a drag bar and depth gadgets. #FRQSAVINGB = %100000000000 ;Are selecting a file to save to. #FRQLOADINGB = %1000000000000 ;Are selecting a file(s) to load from. #FRQDIRONLYB = %10000000000000 ;Allow the user to select a directory, rather than a file. STRUCTURE ========= Below is a description of the Req.Library file requester structure. STRUCTURE AFileRequester,0 UWORD frq_VersionNumber ;MUST BE REQVERSION!!!!!!!!!!!!!!!!!! ;You will probably want to initialize these three variables. APTR frq_Title ; Hailing text APTR frq_Dir ; Directory array (must be DSIZE+1 characters long) APTR frq_File ; Filename array (must be FCHARS+1 characters long) ; If you initialize this variable then the file requester will place the complete path name in here on exit. APTR frq_PathName ; Complete path name array - (must be DSIZE+FCHARS+2 long) ; If you want the file requester to pop up on your custom screen, put one of your window pointers here. ; Or better yet, you can leave this field zeroed and put a pointer to one of your windows in the ; pr_WindowPtr field in your process structure. APTR frq_Window ; Window requesting or NULL ; Initialize these to the number of lines and columns you want to appear in the inner window that ; displays the file names. If you leave these set to zero then default values will be used. UWORD frq_MaxExtendedSelect ; Zero implies a maximum of 65535, as long as FRQEXTSELECT is set. UWORD frq_numlines ; Number of lines in file window. UWORD frq_numcolumns ; Number of columns in file window. UWORD frq_devcolumns ; Number of columns in device window. ULONG frq_Flags ; Various - umm - flags. See above for more info. UWORD frq_dirnamescolor ;These five colors will all default UWORD frq_filenamescolor ;to color one if you don't specify UWORD frq_devicenamescolor ;a color (ie; if you specify color zero). UWORD frq_fontnamescolor ;If you want color zero to be used, specify UWORD frq_fontsizescolor ;color 32, or some other too large number ;which mods down to zero. UWORD frq_detailcolor ;If both of these colors are specified as UWORD frq_blockcolor ;zero then the block pen will be set to one. UWORD frq_gadgettextcolor ;The color for the text of the five boolean gadgets. Defaults to 1. UWORD frq_textmessagecolor ;The color for the message at the screen top. Defaults to 1. UWORD frq_stringnamecolor ;The color for the words Drawer, File, Hide and Show. Defaults to 3. UWORD frq_stringgadgetcolor ;The color for the borders of the string gadgets. Defaults to 3. ;Unfortunately it is not possible to specify ;the color of the actual text in an Intuition ;string gadget. UWORD frq_boxbordercolor ;The color for the boxes around the file and directory areas. Defaults to 3. UWORD frq_gadgetboxcolor ;The color for the boxes around the five boolean gadgets. Defaults to 3. STRUCT frq_RFU_Stuff,36 ;This area, which is reserved for ;future use, should all be zero. STRUCT frq_DirDateStamp,ds_SIZEOF ; A copy of the cached directories date stamp. ; There should never be any need to change this. UWORD frq_WindowLeftEdge; ;These two fields are only used when the UWORD frq_WindowTopEdge; ;FRQABSOLUTEXY flag is set. They specify ;the location of the upper left hand ;corner of the window. UWORD frq_FontYSize ;These fields are used to return the selected UWORD frq_FontStyle ;font size and style, only applicable when the ;font bit is set. ;If you set the extended select bit and the user extended selects, the list of filenames will start from here. APTR frq_ExtendedSelect ; Linked list of ESStructures if more than one filename is chosen. ;All of the following variables you shouldn't need to touch. They contain fields that the file ;requester sets and likes to preserve over calls, just to make life easier for the user. STRUCT frq_Hide,WILDLENGTH+2 ; Wildcards for files to hide. STRUCT frq_Show,WILDLENGTH+2 ; Wildcards for files to show. WORD frq_FileBufferPos ; Cursor's position and first WORD frq_FileDispPos ; displayed character number in WORD frq_DirBufferPos ; the three string gadgets. No WORD frq_DirDispPos ; need to initialized these if WORD frq_HideBufferPos ; you don't want to. WORD frq_HideDispPos WORD frq_ShowBufferPos WORD frq_ShowDispPos ; The following fields are PRIVATE! Don't go messing with them or ; wierd things may/will happen. If this isn't enough of a warning, go read ; the one in intuition.h, that should scare you off. APTR frq_Memory ; Memory allocated for dir entries. APTR frq_Memory2 ; Used for currently hidden files. APTR frq_Lock ; Contains lock on directories being read across calls. STRUCT frq_PrivateDirBuffer,DSIZE+2 ; Used for keeping a record of which ; directory we have file names for. APTR frq_FileInfoBlock WORD frq_NumEntries WORD frq_NumHiddenEntries WORD frq_filestartnumber WORD frq_devicestartnumber LABEL frq_SIZEOF Enjoy! Steve. PCF Library - Picture Crunch Format =================================== -Brought to you by FUNdamental- PCF COMMANDS About This Archive ------------------ This archive contains: o A new library of commands for Blitz Basic 2 o A compiled blitz program to generate PCF files from IFF files o A Blitz Basic and ASCII version of the same demo program, to show use of the commands o A pre-converted image o This file 8) All coding was written by Nigel Hughes, with a thank you to Steve from Reflective Images for his help with AllocDosObject and addressing objects in libraries. Not to mention the excellent RIB libraries. About PCF Format ---------------- On the Blitz mailing list, there was a call for a method of protecting graphics from the "general public" I responded by saying, "Use my library" And then disappeared to prepare for my finals! Well the finals are over and so here is version one of the PCF Library, version 2 will be out soon, more details later. PCF is more compact graphics file format, that cannot be read by any general release paint package. There are commands within the library to cache these pictures and decompress to a bitmap only when you need them. Later versions will enable a coder to add his own personal tag so only he/she can decrypt the file. Making a PCF Picture -------------------- In order to turn a IFF ILBM picture into a PCF file one need only use the picture_crunch program supplied in the archieve. Click on the "Load N Crunch" button to load an IFF and convert it to a PCF file. You will be asked if you wish to generate a V 1.0 file or the latest format. Please only select the "Latest Format" option as V1.0 is reserved for my use only and is protected and cannot be decrypted by any one else! One can only use the Display gadgets once a IFF picture has been crunched, this is a bug that will be fixed in later versions. Sorry. The Library ----------- The library can be installed either by copying "PCF_Lib.obj" to your BlitzLibs:Userlibs directory and then selecting "RELOAD ALL LIBS" in the COMPILER menu in BB2, or by using the MakeDefLibs program after copying "PCF_LIb.obj" to your BlitzLibs:Userlibs directory. PCF Commands: CACHEPCF FREEPCFCACHE LOADPCF UNPACKPCF PCFDEPTH PCFHEIGHT PCFINFO PCFVERSION PCFWIDTH OTHER INFO Function : CachePCF -------------------------------------------------------------------------- Modes: Amiga Syntax: cache_ptr.l=CachePCF (Filename$,Memory Type,Cache Length) The function loads a PCF file into memory, returning the pointer to the cache. The Cache Length variable will contain the length of the cache and is needed in order to use the FreePCFCache command. This command does not cause the PCF image to be displayed. If anything goes wrong during the loading of the file, no memory will be allocated and 0 will be returned. See Also: FREEPCFCACHE , LOADPCF , UNPACKPCF Statement: FreePCFCache -------------------------------------------------------------------------- Modes: Amiga/Blitz Syntax: FreePCFCache cache_ptr,cache_length Frees the memory used by the PCF cache. See Also: CACHEPCF Statement: UnpackPCF -------------------------------------------------------------------------- Modes: Amiga/Blitz Syntax: UnpackPCF Bitmap#,Palette#,cache_ptr Decompresses a PCF cache to a bitmap and palette. Both objects must already exist. The PCF library currently makes no attempt to check the bitmap or the palette are deep enough. If the bitmap is too large then the image WILL be corrupt. The statement checks the version of PCF Cache to ensure that it can decompress it! See Also: CACHEPCF , LOADPCF Statement: LoadPCF -------------------------------------------------------------------------- Modes: Amiga Syntax: LoadPCF Bitmap#,Palette#,cache_ptr Loads and decompresses a PCF image straight into the bitmap and palette. The image is NOT cached afterwards. The same restriction apply to this command as to UnpackPCF See Also: CACHEPCF , UNPACKPCF Statement: PCFInfo -------------------------------------------------------------------------- Modes: Amiga/Blitz Syntax: PCFInfo cache_ptr Enables the use of PCFWidth, PCFHeight, PCFDepth, PCFVersion. These commands will all return the relevant details about the cache pointed to by cache_ptr. This allows a programmer to ensure that the destination bitmap and palette are of the correct dimensions. See Also: PCFWIDTH , PCFHEIGHT , PCFDEPTH , PCFVERSION Function: PCFVersion -------------------------------------------------------------------------- Modes: Amiga/Blitz Sytax: v.l=PCFVersion Returns the version of the last cache interogated by PCFInfo. Function: PCFWidth -------------------------------------------------------------------------- Modes: Amiga/Blitz Sytax: v.l=PCFWidth Returns the width of the last cache interogated by PCFInfo. Function: PCFHeight -------------------------------------------------------------------------- Modes: Amiga/Blitz Sytax: v.l=PCFHeight Returns the height of the last cache interogated by PCFInfo. Function: PCFDepth -------------------------------------------------------------------------- Modes: Amiga/Blitz Sytax: v.l=PCFDepth Returns the number of bitplanes of the last cache interogated by PCFInfo. Performence ----------- The UnpackPCF command can decompress a 320x256 by 256 colour image in under 10/50 of a second. For an image of 5 bitplanes or lower, the command can often decompress in under a frame. The PCF file format itself is usually about 1k smaller than the related IFF file. This ratio will be much improved in the next version. The Futre --------- I have a HUGE list of things to do, I just really wanted to get this out to the general public so people can tell me what they think (wince). But futre enhancements will include... o A PackIFF type command o Improved Compression rate o Unique key for decompression o Multiple file types, including Shapes o Multiple files in one PCF file. Any bugs etc please contact FUNdamental at Nigel Hughes 2 Slimmons Drive St. Albans Herts AL4 9AS Until the 23rd Of June at nlh1@k.ac.aber, and after that via Mike Richards at mhr@k.ac.aber. Right, it is 1:05 AM and I am going to bed... Nigel Hughes. BACK TO MAIN PACK Library v0.1 ================= By Stephen McNamara with a little help from Steve Matty (c)1994 Reflective Images PACK COMMANDS This library contains commands for the unpacking of ILBM's (IFF pictures) and the grabbing of their palettes (CMAP chunks). Nearly all the commands in this library can be used as either STATEMENTS or FUNCTIONS. Usage is identical in both cases but if used as a function then the command will return: FALSE for failure TRUE for success Please feel free to critisise (or praise!) this library, send me anything you want to say about it at: Stephen McNamara, 17 Mayles Road, Southsea, Portsmouth, Hampshire, England. PO4 8NP. Telephone: (England) 0705 781507. Or send us anything you've written........ These are all the PACK library commands: DEICE ILBMGRAB ILBMPALETTE LOADIFF =LOADIFF UNPACKIFF =CHUNKHEADER =DEICE =ILBMPALETTE =UNPACKIFF Statement/Function: UnpackIFF -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: UnpackIFF address.l,bitmap#[,lines] suc=UnpackIFF (address.l,bitmap#[,lines]) This command is used to unpack an IFF picture file from memory onto a bitmap. Address.l should point to the START of the iff file header in memory (either CHIP or FAST mem can be used), bitmap should be the number of a previously initialised bitmap. The optional lines parameter allows you to specify the number of lines to unpack from the IFF file. This command checks the size of the bitmap against the size of the IFF before it unpacks the IFF onto it. Checks are made for width, height and depth of the bitmap and the IFF and the following is done: (size=WIDTH, HEIGHT and DEPTH) BITMAP 'size' < IFF 'size' : unpack aborted BITMAP 'size' = IFF 'size' : pic is unpacked BITMAP 'size' > IFF 'size' : pic is unpacked Extra aborts can be caused by: - not using a previously installed bitmap - given the optional lines parameter as 0 or less - not giving ADDRESS.l as a pointer to a valid IFF ILBM header When using the optional parameter, you should note that if you try to unpack more lines than the IFF has, the unpack routine will automatically stop at the last line of the IFF. It will not reject the UnpackIFF command. NOTE: you should save your IFF pictures with the STENCIL OFF because at the moment this routine does not check to see if STENCIL data is present in the IFF file. Statement/Function: ILBMPalette -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ILBMPalette address.l,palette# suc=ILBMPalette (address.l,palette#) This command is used to grab the palette from a IFF picture file held in memory (CHIP or FAST mem). Address.l should be given as the address of either an IFF file in memory or a CMAP chunk in memory. When you use the SAVE PALETTE command from inside an art program (e.g. DPaint) or from inside Blitz2, the program saves out a CMAP chunk which gives details about the palette. The CMAP chunk is also saved with IFF picture files to give the palette of the picture. This command will look at the address you gave and try and find a CMAP chunk from the address given to address+5120. If it finds a chunk it will grab the palette into the given palette object. If the palette object already contains palette information then this information is deleted. This routine looks in the CMAP chunk and reserves the palette object to have the same number of colour entries. This command will fail if it doesn't find a CMAP chunk. Statment: ILBMGrab ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ILBMGrab address.l,bitmap#,palette# This command lets you grab both the palette and the graphics from an IFF picture file with just one command. It returns to success parameter to say whether or not it succeeded in grabbing the data, so if you need to know if the grabbing was successful you'll have to use the separate commands for grabbing palettes and graphics. NOTE: this command essentially just calls both UNPACKIFF and ILBMPALETTE so everything said about these commands is relevent for ILBMGrab. Statment/Function: LoadIFF ------------------------------------------------------------------------- Modes : Amiga Syntax: LoadIFF filename$,bitmap#[,palette#] suc=LoadIFF (filename$,bitmap#[,palette#]) This command is a direct replacement for Blitz2's LoadBitmap. It is a lot faster than Blitz's command since it loads the file into memory and then unpacks it from there. Thus you need to ensure that you have enough free memory to load the IFF into before trying to use this command. This command is also more stable than Blitz's since it checks for the existence of the file before trying to load it in. The optional parameter allows you to load in the palette of the IFF picture. Refer to UnpackIFF and ILBMPalette for more information about unpacking the graphics and grabbing the palettes. IMPORTANT NOTE: to use this command you must have our FUNC library installed in your copy of Blitz2. Use of this command without this library will probably lead to a bad crash of your Amiga! Statement/Function: DeIce ------------------------------------------------------------------------- Modes : Amiga Syntax: DeIce source_address,dest_address suc=DeIce (source_address,dest_address) This is a command from my (Stephen McNamara) past. It is used to unpack data files packed by my favourite Atari ST packer - PACK ICE v2.40. I've put it into Blitz because still have loads of files that I've packed with it. To use it, source_address should (obviously) contain the address of the data, dest_address should be where to unpack the data to. In the function form, this command returns either 0 for unpack failed or -1 for success. Note: The size of the data unpacked is the long word at source_address+8 (I think, or is it 4?) if anybody is interested...... Function: ChunkHeader ------------------------------------------------------------------------- Modes : Amiga Syntax: val.l=ChunkHeader (A$) This command was put in by me (Stephen McNamara) before I realised Blitz already had a command that does exactly the same. I've left it in just because I want to. It is useful when looking through IFF files for chunks (e.g. ILBM, CMAP, etc.) as it gives you a longword value to look for in memory to find the chunk. The string should be a four character string (e.g. CMAP), you'll be returned the longword value of the string. This command does the job of the following bit of Blitz2 code: a$="CMAP" val.l=Peek.l(&a$) GFX Library v0.1 ================ By Stephen McNamara and Steve Matty (c)1994 Reflective Images GFX COMMANDS This library contains commands for the control of palette objects inside Blitz2. These are just simple commands that allow either interrogation of the palette objects are modifications to the colour values contained in them. After changing the palette with these commands, you'll have to do either a USE PALETTE or DISPLAYPALETTE (whichever is applicable to what you're doing) to make the changes come into effect on your screen. Please feel free to critisise (or praise!) this library, send me anything you want to say about it at: SIS3149@ISVAX.PORT.AC.UK or SIS3147@ISVAX.PORT.AC.UK Or send us anything you've written........ These are all the GFX library commands: AGAFILLPALETTE FILLPALETTE PALADJUST PALETTEINFO =PALRED =PALGREEN =PALBLUE =AGAPALRED =AGAPALGREEN =AGAPALBLUE Statement: PaletteInfo -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: PaletteInfo Palette# This command is used to specify the palette object that all palette interrogations should look at. The majority of the commands use this palette object as the source for their data, e.g. PalRed(1) will look at the red value of colour 1 of the palette last used in a PaletteInfo command. -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: r.w=PalRed (Colour#) This command is used to get the red value of colour number Colour#. You should use the PaletteInfo command to specify what palette this command takes its information from. The value returned will be from 0 to 15 Function: PalGreen ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: r.w=PalGreen (Colour#) This command is used to get the green value of colour number Colour#. You should use the PaletteInfo command to specify what palette this command takes its information from. The value returned will be from 0 to 15 Function: PalBlue ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: b.w=PalBlue (Colour#) This command is used to get the blue value of colour number Colour#. You should use the PaletteInfo command to specify what palette this command takes its information from. The value returned will be from 0 to 15 Function: AGAPalRed ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: r.w=AGAPalRed (Colour#) This command is used to get the red value of colour number Colour#. You should use the PaletteInfo command to specify what palette this command takes its information from. The value returned will be from 0 to 255, this number of shades, though, can only be displayed on an AGA machine. Function: AGAPalGreen ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: g.w=AGAPalGreen (Colour#) This command is used to get the green value of colour number Colour#. You should use the PaletteInfo command to specify what palette this command takes its information from. The value returned will be from 0 to 255, this number of shades, though, can only be displayed on an AGA machine. Function: AGAPalBlue ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: b.w=AGAPalBlue (Colour#) This command is used to get the blue value of colour number Colour#. You should use the PaletteInfo command to specify what palette this command takes its information from. The value returned will be from 0 to 255, this number of shades, though, can only be displayed on an AGA machine. Statement: PalAdjust ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: PalAdjust dest_palette#,ration.q[,start_col,end_col] This command is used to multiple all the colours, or a range of colours, in a palette object, by a ratio. The dest_palette# arguement is used to give a destination for the adjusted colour information. This destination should be a pre-reserved palette and should be AT LEAST as big and the source palette. The source palette is taken as being the palette last used in the PaletteInfo command. The ratio should be given as either a quick value or a float and should be below one for a fade or above to lighten a palette. If you give a ratio of 1 then a palette copy will occur. The optional start and end parameters let you specify the range of colours to adjust. Only this range of colours, though, will be adjusted and stored in the destination palette. Statement: FillPalette ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FillPalette palette#,r,g,b[start_col,end_col] This command lets you fill a given palette object with specific r,g,b values. The values given should be between 0 to and 15. Optionally, you can give start and end colour numbers to set a range for the fill. You should be careful, though, because when you specify a range, no checking is done (at the moment) to make sure that you don't exceed the colour limit of the palette. You should note that this command does not work on the palette last PaletteInfo'ed. Statement: AGAFillPalette ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: AGAFillPalette palette#,r,g,b[start_col,end_col] This command is identical to FILLPALETTE except that it lets you specify AGA shade values for the r,g,b parameters. See FILLPALETTE for more information. FNS Library v0.992 ================== By Stephen McNamara (c)1994 Reflective Images FNS COMMANDS This Blitz2 library prints proportional fonts in either Amiga or Blitz mode. It uses my own (rather primitive) font file format, details of which can be found at the end of this text file. Fonts can be upto 64 pixels wide and any height (although the font editor is limited to 64 pixels at the present moment). Fonts can be output in upto 256 colours (AGA!) and in the following ways: bold, centred, underlined, right- aligned or just standard left-aligned. Note: a default font (PERSONAL.8) is built into this library and can be used by simply using font number 0. You do not have to install this font, it is automatically available for your use. A second point is to make is that the library is set up with a clipping rectangle of 0,0 to 0,0. Thus you have to use either FNSClip, FNSClipOutput or FNSOutput (with the optional clip parameter) to set the clipping rectangle before you try to print anything. Please feel free to critisise (or praise!) this library, send me anything you want to say about it at: SIS3149@ISVAX.SIS.PORT.AC.UK Or send me anything you've written........ These are all the FNS library commands: INSTALLFNS =FNSHEIGHT REMOVEFNS =FNSLENGTH FNSCLIP =FNSLOAD FNSCLIPOUTPUT =FNSSLOT FNSSETTAB =FNSUNDERLINE FNSINK =FNSVERSION FNSORIGIN =FNSWIDTH FNSOUTPUT FNSPREFS FNSPRINT FNSUNLOAD FNS FONT FORMAT Note: All return values will be words except when using InstallFNS and FNSVersion. FNS Font file format: ===================== Header: 256 bytes. 0-3 : 'FNS.' - file identifier - looked for by InstallFNS 4-5 : height of font (#word) 6-7 : width of font in multiples of 16 (#word) 8-9 : underline position (offset from top of font, #word) 10-11 : size of data for each font character [ (WIDTH/8) * height ] 32-255: byte giving widths of each character in the font. These bytes doesn't really hold the width, rather they hold the value to add to the X position of the character to get to the position to print the next character at (!). 256-EOF:character data starting at ASCII 32 (space) Statement: FNSSetTab ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSSetTab tab_width Description: Use this command to set the tab spacing used when printing. The value given should be the spacing IN pixels. Function: FNSLoad -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: suc=FNSLoad (filename$,font#) Description: This command is used to load a font from disk and automatically install it for use by the FNS commands. Filename$ should be the full name of the file to load (path$+file$) and font# should be 0<= and >=15. This command returns a value of -1 for failure or the font number the font was installed as (see InstallFNS). A failure could either be a load error or an installation error. You should make sure that the file you load IS an FNS font file. IMPORTANT NOTE: to use this command, you must have our FUNC library installed on your copy of Blitz2. Running it without this library could, and probably will, cause a major crash of your computer. Also note that if you do an ERASEALL (this is a FUNC library command for erasing banks), you will DELETE your font from memory! Statement: FNSUnLoad -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSUnLoad font# This command is used to remove a font installed with the FNSLoad command. When this command runs it automatically removes the font entry in the FNS commands and deletes the memory that the font file is held in. There is no need to do this at the end of a program as the FUNC library automatically frees up all allocated memory. Function: FNSSlot ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: address.l=FNSSlot Steve: this command was not in the doc file. Function: InstallFNS ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: font_num.b=InstallFNS(font_num.b,address.l) This is used to install a font so that it is available for use by the output routines. Font_num should be a number >=0 and <=15, address should be the address in memory of the FNS font file. This function will check that the address given does contain a FNS font (it will look for the header 'FNS.'), if it cannot find the font or something else goes wrong it will return a 0 to you, otherwise it will return the number the font was installed as. Note: The font number you give is automatically ANDED with $F when you call this function, thus if you supply a number greater that 15 you could actually overwrite a previously installed font. See: REMOVEFNS Statement: RemoveFNS ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: RemoveFNS font# This command simply removes an installed font from the list of font held internally by the FNS routines. There is no real need to remove fonts as installing fonts takes up no memory, except of course the actual font data. You do not need to remove FNS fonts before ending a program. See: INSTALLFNS Statement: FNSPrint ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSPrint font_num.b,x.w,y.w,a$/string_address [,preferences,colour] This command prints the string a$ in an FNS font at the position X,Y. Font_num is the number of a previously installed FNS font, the output of this command is sent to the current FNS bitmap (see FNSOutput). You can setting a drawing rectangle on the currently used bitmap to limit the output of the font - see FNSClip for more info. Instead of a string, though, you can give the address of a null terminated string in memory. Also, you can change the colour that text is being output in in the current string by putting the character ASCII 1 followed by a byte value from 0-255 specifying the colour to change to. The optional parameters are for controlling how the text is output. They automatically overide the default setting but are not permanent, i.e. the default output style and colour are restored after the line has been output. Use FNSInk and FNSPrefs to set the default font output mode. See: FNSOUPUT , FNSINK , FNSPREFS , FNSORIGIN , FNSCLIP Statement: FNSOutput -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSOutput bitmap#[,clip_update] This command selects a bitmap for use by the FNS routines, the bitmap must be a previously reserved Blitz 2 bitmap object. After this command all FNS font printing will occur on the selected bitmap. The optional parameter allows you to update the clipping rectangle for output at the same time as setting the output bitmap. Setting clip_update to a non-zero value will cause the clipping area to automatically be set to the dimensions of the selected bitmap. NOTE: ----- This command MUST be used before you attempt to use FNSPrint. The maximum depth of the bitmap for printing is 8 bitplanes since this is all Blitz 2 currently supports. See: FNSCLIP , FNSCLIPOUTPUT Statement: FNSInk ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSInk colour# This sets the output colour for the FNS font drawing routines. The number range is dependant on the depth of the destination bitmap, the max posible range, though, is limited to 0 to 255 colours. The FNS output routines will attempt to draw in all the bitplanes of the selected bitmap, any extra bits in the ink colour will be ignored. See: FNSPREFS Statement: FNSPrefs ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSInk preferences[,colour#] This sets the output prefs for the FNS font drawing routines but at the same time also sets the colour for the FNS routines (optional). At the moment the following options are available, the bits of the preferences byte are used to select the different options: bit 0: Centred text bit 1: Bold text bit 2: Underline bit 3: Right aligned See: FNSINK , FNSPRINT , FNSLENGTH Function: FNSHeight ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: height.w=FNSHeight(font_num) This routine returns the height of a previously installed FNS font. Font_num should be >=0 and <=15. See: FNSUNDERLINE , FNSWIDTH Function: FNSUnderline ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: under_pos=FNSUnderline(font_num) This routine returns the underline position of the selected FNS font. Font_num should be >=0 and <=15. See: FNSHEIGHT , FNSWIDTH Function: FNSWidth ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: width.w=FNSWidth(font_num) This routine returns the width in multiples of 16 of the selected FNS font. Font_num should be >=0 and <=15. See: FNSHEIGHT , FNSUNDERLINE Statement: FNSClip ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSClip x1,y1,x2,y2 This command is used to limit the output of the FNSPrint command. The co-ordinates given should describe a rectangle that is to be used to clip the output. This rectangle can be thought of as a window on the bitmap - no printing can occur outside of the window. X1,Y1 are the top left corner of the clipping rectangle and X2,Y2 are the bottom right corner. Please note that both X co-ordinates should be multiples of 16 and that X2 should be the heightest multiple of 16 that you do not wish output to occur at. Thus if your bitmap is 320x256 then you would use the following to set the clipping rectangle to the full bitmap: FNSClip 0,0,320,256 See: FNSCLIPOUTPUT , FNSOUTPUT Statement: FNSClipOutput ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSClipOutput This command is used to quickly set the clipping rectangle for the FNS commands to the full size of a bitmap. See: FNSCLIP , FNSOUTPUT Statement: FNSOrigin ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FNSOrigin [x,y] This command is used to set an origin co-ordinate for printing output. Whenever you use FNSPrint, the origin co-ordinates are added (as words) to the co-ordinates you give for output. I.e. setting the origin at 100,0 and printing at co-ordinates 0,0 will cause the output to be at 100,0. Using this command without any parameters will cause the origin to be reset to the position 0,0. Note: This command does not affect the use of the FNSClip command. Function: FNSLength ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: a=FNSLength (font#,a$[,prefs]) This command is equivalent of the basic command a=len(a$) except that it returns the x size, in pixels, of the string if it were to be printed in the font font#. The optional preferences parameter allows you to adjust the output of the string, if you specify no preferences then this function will use the previously selected preferences to calculate the string length. Using preferences allows you to account for things like bold text output. See: FNSPREFS Function: FNSVersion ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: a.q=FNSVersion This command allows you to test the version number of the FNS library that your program is being compiled with. It returns a quick float value and so you should use a quick float variable for the answer. This doc file was written for version 0.991 of the library. FNS Font file format: ===================== Header: 256 bytes. 0-3 : 'FNS.' - file identifier - looked for by InstallFNS 4-5 : height of font (#word) 6-7 : width of font in multiples of 16 (#word) 8-9 : underline position (offset from top of font, #word) 10-11 : size of data for each font character [ (WIDTH/8) * height ] 32-255: byte giving widths of each character in the font. These bytes doesn't really hold the width, rather they hold the value to add to the X position of the character to get to the position to print the next character at (!). 256-EOF:character data starting at ASCII 32 (space) Func/AMOS Library v1.0 ================= By Steven Matty ©1994 Reflective Images FUNC COMMANDS This library was written primarily to emulate the functions that were present in AM*S but not in Blitz Basic 2. It began life as a load of Blitz Statements but was then converted to high speed 680x0. The library will continually be expanded upon and free updates will be sent on request. If you decide to use any of the function please give me a little cred, not a lot, just something. Anyway, enough of this baloney....on with the command list. These are all the FUNC library commands: CACHEOFF =KEYCODE COPYBYTE =LENGTH COPYWORD =LISA COPYLONG =MAKEDIR ERASE =MAX ERASEALL =MEMFREE FILLMEM =MIN NEXTBANK =PLOAD REBOOT =RENAME RESETTIMER =RESERVE =BLOAD =CLUDGESHAPES =BSAVE =CLUDGESOUND =FILESIZE =START =XOR =TIMER ********************************* NOTE ************************************** * VALID BANKS RANGE FROM 0-49 INCLUSIVE. DO NOT USE A VALUE GREATER THAN 49 * * OR IT WILL BE INTERPRETED AS AN ADDRESS RATHER THAN A BANKNUMBER * ***************************************************************************** Statement: ResetTimer -------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : ResetTimer This will recent the CIA timer to 0. Statement/Function : CludgeShapes -------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : [success]=CludgeShapes(shape#,numshapes,address) This allows the creation of shapes through INCBIN statements. It allocates chip memory for each shape and copies the data into this. It does the same as LoadShapes except it grabs shapes from memory. Statement/Function : CludgeSound -------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : [success]=CludgeSound(sound#,address) This does that same for CludgeShapes but works on only 1 sound at a time NOTE: Looped sounds are not currently supported! The sound must be a valid 8SVX sample. Function: Reserve -------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : success=Reserve(banknumber,length) This will attempt to reserve <length> bytes of memory. If succesfull, it will return the address of the bank. If unsuccessfull, 0 is returned. Banks are limited by the Compiler Options Menu. Statement: Erase -------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : Erase(banknumber) The Erase command will erase the specified memory bank. Statement: EraseAll -------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : EraseAll This command will erase ALL allocated memory banks. Function: BLoad ------------------------------------------------------------------------- Mode : Amiga Syntax : success=BLoad(filename$,bank/address[,length,offset]) If bank is specified, then the file is loaded into that bank. If address is specified then it is loaded to the address. Valid banks are 0-49. If the bank does not exist, Blitz will reserve a bank for you. If the bank does exist, Blitz will erase the bank from memory, and allocate a new one. The return result is -1 for success, or 0 for failure (not enough RAM, file not exist). If offset is specified, then <length> bytes will be read from the specified offset position in the file. Function: PLoad ------------------------------------------------------------------------- Mode : Amiga Syntax : success=PLoad(filename$,bank/address) This will attempt to load the executable file to the specified address. -1 is success, 0 is failure. Function: BSave ------------------------------------------------------------------------- Mode : Amiga Syntax : success=BSave(filename$,bank/address,length) This will save <length> bytes at bank/address to the file. Return result is -1 for success, 0 for failure. If length > bank length then the length of the bank is saved instead. If 0 is specified, the entire bank is saved. Function: Start ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : start_address.l=Start(banknumber.b) This will return the start address of the specified bank. (0=no bank) Function: Length ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : length_of_bank.l=Length(banknumber.b) This will return the length of the specified bank in bytes. (0=No bank) Function: MemFree ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : bytes.l=MemFree This will return the total amount of Public Free RAM available to the system. Function: NextBank ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : bank.b=NextBank This will return the number of the first available bank (-1 if none free). Statement: FillMem ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : FillMem(address.l,length.l,value.b) This will fill 'length' bytes starting from the specified address with 'value'. Statement: CopyByte ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : CopyByte(source.l,dest.l,num.l) This will copy <num> bytes from <source> to <dest> Statement: CopyWord ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : CopyByte(source.l,dest.l,num.l) This will copy <num> words from <source> to <dest> Statement: CopyLong ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : CopyByte(source.l,dest.l,num.l) This will copy <num> longwords from <source> to <dest> Function: MakeDir ------------------------------------------------------------------------- Mode : Amiga Syntax : success=MakeDir(name$) This function attempts to create a directory called <name$> If it is unsuccessfull, 0 is returned else -1 is returned. Function: Rename ------------------------------------------------------------------------- Mode : Amiga Syntax : success=Rename(source$,dest$) This attempts to rename the file <source$> to <dest$> NOTE: It is not possible to rename across devices. -1 is returned if successfull, else 0. Function: Timer ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : t.l=Timer This will return the number of 50ths of a second since startup. Function: Lisa ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : chipver=Lisa This will return the current Lisa chip version : $00 for OCS Denise $F7 for ECS Denise $F8 for AGA Lisa Statement: Reboot ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : Reboot This will perform a cold reboot Function: FileSize ------------------------------------------------------------------------- Mode : Amiga Syntax : size.l=FileSize(filename$) This return the length (in bytes) of the file. Statement: CacheOff ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : Cache Off This will turn off the instruction cache of the CPU. Function: XOR ------------------------------------------------------------------------- Mode : Amiga/Blitz Syntax : x.l=XOR(x.l,y.l) This will perform an Exclusive-Or operation between X and Y and put the result back into X e.g x=XOR(%101,%100) Will place %001 into X (%101 XOR %100 = %001) Function: Max/Min ------------------------------------------------------------------------ Mode : Amiga/Blitz Syntax : value=Max(first_var,second_var) value=Min(first_var,second_var) This will compare both values and return either the Higher of the values (Max) or the Lower (Min). This currently supports INTEGERs only. Function: KeyCode ------------------------------------------------------------------------ Mode : Amiga/Blitz Syntax : keycode=KeyCode This will return the status of the keyboard in the form of a keycode. You will need to experiment to find out the desired keycode for a particular key. This merely peeks address $bfec01 and returns the value found. Reflective Images Effects Library ================================= By Stephen McNamara, with help from Steve Matty (c)1994 Reflective Images FX COMMANDS Note: The library has had a lot of the commands inside it expanded so that they work on any size bitmap. At the moment the following, though, will only work on lorez bitmaps: ZoomX8, Derez and ZoomXY None of the commands in this library use the blitter chip, any blitter source code that anybody has please send to me. Here are all the FX commands: Command list: CHUNKYTOPLANAR (SLOW) CLEARBITMAP DEREZ FADEINBITMAP INITZOOMXY PLANARTOCHUNKY (SLOW) REDUCEX2 ZOOMXY ZOOMX2 ZOOMX4 ZOOMX8 =ADDVALUE(BITMAP#,X,Y) No instructions for the planar<>chunky commands since their not really that useful at the moment. If anybody has some working code thats good then....................... No instructions for the planar<>chunky commands since their not really that useful at the moment. What I'm going to try and do is put some faster conversion routines in this library to do the jobs of these commands. Statement: FadeInBitmap -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: FadeInBitmap source#,dest#,delay[,offset1,offset2,height] This is used to make a low rez, any height, bitmap appear on another one in a nice way. Source# and dest# should be bitmap object numbers and delay is the 'slow-down' value for the fade. This is necessary because this routine works very fast - at full speed it looks just like a slow screen copy. You should note that the delay is taken as being a word, thus don't pass 0 or you'll actually get a delay of 65535. This routine will adjust itself to take into account the depth of the bitmap, WARNING: the depth of the destination bitmap should be AT LEAST as big as the depth of the source# bitmap because the depth of the fade is taken from the source# bitmap. The optional parameters in this command allow you to set respectively: the source bitmap y offset, the destination bitmap y offset and the height of the fade (in pixels). If these parameters are left out then the fade automatically occurs across the full size of the bitmap. See: CLEARBITMAP Statement: ClearBitmap -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ClearBitmap source#,delay[,offset,height] This is used to clear a low res, any height, bitmap in a very pleasant way. The parameters are the same as for FadeInBitmap except that only one bitmap is needed. The delay parameter i used for the same reason as in FadeInBitmap - to slow down the effect. The optional parameters allow you to set a y start value for the clear and the height (in pixels) of the clear. See: FADEINBITMAP Statement: ZoomX2 -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ZoomX2 source#,dest#,add_source,add_dest,width,height This command does a very fast X2 zoom. It works with two bitmaps - one source and one dest (note: these can be the same bitmap but you should be careful that the zoom is not done over the source data). The two parameters add_source and add_dest allow you to specify the position of the start of the zoom, they specified as byte offsets from the top left corner of the bitmaps (byte 0). These values can be calculated by the following method: add_source=(Y x BITMAP_WIDTH (in bytes) + (X / 8) or by using the built in command ADDValue. Width and height are both specified in pixels. NOTE: There is no clipping on this command - be careful not to zoom off the edges of bitmaps. you can zoom from a bitmap to a different size bitmap BUT the destination bitmap must be as deep as the source and big enough to hold the zoomed data. See: ZOOMX4 , ZOOMX8 , ADDVALUE Statement: ZoomX4 -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ZoomX4 source#,dest#,add_source,add_dest,width,height This is exactly the same as ZoomX2 except that a times 4 zoom is done by this command. Note: You can zoom from a bitmap to a different size bitmap BUT the destination bitmap must be as deep as the source and big enough to hold the zoomed data. See: ZOOMX2 , ADDVALUE Statement: ZoomX8 -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ZoomX8 source#,dest#,add_source,add_dest,width,height This is exactly the same as ZoomX2 except that a times 8 zoom is done by this command See: ZOOMX2 , ADDVALUE Function: ADDValue -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: addval.w=ADDValue(bitmap#,x,y) This function can be used the calculate the add_source and add_dest values used in all the zoom commands. Just give the bitmap number, x co-ordinate and the y co-ordinate and you'll get an answer back that can be used straight in the ZoomXn commands. See: ZOOMX2, ZOOMX4 , ZOOMX8 , ZOOMXY Statement: InitZoomXY -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: InitZoomXY source#,dest#,add_source,add_dest This command initialises the ZoomXY routine to the bitmaps you want it to work on. You MUST use this routine before calling ZoomXY. The parameters are the same as the first four parameter for the ZoomXn commands - source and dest bitmaps and add_source/dest values. See: ZOOMXY Statement: ZoomXY -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ZoomXY xzoom_value,yzoom_value,height This command does a zoom based on the values you give it. You should note, though, that zoom values should be integer values (no fractional part). The height is the height in pixels that the source data should be zomed to. Please note that this command is different to the other zoom commands in that the output of it is clipped to fit inside 320 pixels. This command should only be used after InitZoomXY has been called. This routine has an extra feature in that if you give both zoom values as 1 then a bitmap copy is done from the source to the dest using the offsets given and the height. See: INITZOOMXY Statement: Derez -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: Derez source#,dest#,add_source,add_dest,derez_value,height This command is used to derez a low resolution bitmap onto another one. The bitmaps are source# and dest#, add_source and add_dest are used to control the start position of the derez (see ZoomX2 and ADDValue to see how these are calculated). The derez value if obviously the amount that each pixel will be derezed to in both the x and y directions, the height is the height of the derez - the derez is clipped to fit inside this in the y direction and inside 320 pixels in the x direction. This routine has an extra feature in that if you give derez_value as 1 then a bitmap copy is done from the source to the dest using the offsets given and the height. Statement: ReduceX2 -------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax: ReduceX2 source#,dest#,add_source,add_dest,width,height Description: This command halves the given rectangle of one bitmap and pastes it onto the destination bitmap. Width should be a multiple of 16, width and height should describe a rectangular area that will be reduced (these values should be in pixels). See ZOOMX2 and other commands for more information about the syntax of this command. Reflective Images Zone-Joystick Library v1.2 ============================================ By Stephen McNamara, original Joy Library by Steve Matty (c)1994 Reflective Images This library contains commands for setting up zones and testing the status of the joysticks attached to the Amiga. ZONE-JOY COMMANDS @NDNODE Zone-Joy commands: Command list: FREEZONETABLE NEWZONETABLE SETZONE USEZONETABLE ZONEINIT =ALLFIRE =JFIRE =JHORIZ =JVERT =ZONETABLESIZE =ZONE =ZONETEST =ZONETABLE Function: ZoneTableSize ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : size.l=ZoneTableSize This function returns the size, in zones, of the current zonetable. It is equivalent of doing: size.l=peek.l(ZoneTable). Statement/Function: UseZoneTable ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : UseZoneTable table# This command is used to change the current zonetable to the selected one. If used as a function, it will return TRUE for success or FALSE for failure. Valid zonetable numbers range from 0 to 15. Statement/Function: NewZoneTable ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : NewZoneTable table#,size This command will attempt to allocate a new zonetable with the given table number. If the table already exists it will be deleted. The maximum size for a zonetable is 65536 zones. If used as a function, this command will return FALSE for failure or TRUE for success. You should note that all zones are automatically reset in the new table and that creating a table does not make it the current table, this must be done with UseZoneTable. Valid zonetable numbers range from 0 to 15. IMPORTANT NOTE: you cannot define the size of zonetable 0. You cannot use this command to alter it in any way. Statement/Function: FreeZoneTable ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : FreeZoneTable table# This command is used to free a zonetable from memory. If used as a function, it will return TRUE or FALSE. When successfully called, this command will free the zonetable and change the currently used zonetable to table number 0. Valid zonetable numbers range from 0 to 15. IMPORTANT NOTE: you cannot free zone table 0. Function: ZoneTable ------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : ad.l=ZoneTable This function returns the address in memory of the zone information storage area for the current zonetable. The zones are stored one after the other, with each zone taking up 8 words (16 bytes) in the data area, making a total size of 2048 bytes. They are stored in the following way: Rectangular: +0: x1 +2: y1 +4: x2 +6: y2 Circular: +0: x1 +2: y1 +4: radius of zone +6: -1 <-- this is set to show that the zone is circular. Undefined zone: +0: -1 +2: -1 +4: -1 +6: -1 The first longword (4 bytes) of the zonetable is used to hold the size, in zones, of the table (thus the true size of the zonetable is 4+number of zones*8). Statement: ZoneInit --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : ZoneInit [zone_num]|[start_zone,end_zone] This command is used to clear any zones currently set. The optional parameters allow you to select either a single zone or a range of zones to reset. Statement: Setzone --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : Setzone zone#,x1,y1,radius Setzone zone#,x1,y1,x2,y2 This command lets you set up zones for testing. The first version is used when you want to set up a circular zone and the second when you want a rectangular one. With rectangular zones, x1,y1 should be the top left corner of the rectangle and x2,y2 should be the bottom left. Note: The max zone number is 255. When you use this command, the zone number you give is ANDed with 256 so you should ensure that you give a number lower than 256 so that previously defined zones don't get corrupted. Zones can be defined in any order. Circular zones are used in exactly the same way as rectangular ones. Function: Zone --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : a.w=Zone(x,y) This command takes the co-ordinates x,y and checks to see if they are inside any of the defined zones. The zones are searched in order, starting at 0 and going through to 255. This command will return the first zone that the co-ordinates were found to be inside, you should note that both types of zones are tested (rectangular and circular). This command returns either -1 for not inside a zone or the zone number. Function: ZoneTest --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : a.w=ZoneTest(start_num[,end_num],x,y) This command is the same as the Zone command except that it allows you to select either one individual zone to test or a range of zones. You should, though, ensure that end_num if greater than start_num. This command returns either -1 for not inside a zone or the zone number. Function: ZoneTable --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : ad.l=ZoneTable This function returns the address in memory of the zone information storage area. The zones are stored one after the other, with each zone taking up 8 words (16 bytes) in the data area, making a total size of 2048 bytes. They are stored in the following way: Rectangular: +0: x1 +2: y1 +4: x2 +6: y2 Circular: +0: x1 +2: y1 +4: radius of zone +6: -1 <-- this is set to show that the zone is circular. Undefined zone: +0: -1 +2: -1 +4: -1 +6: -1 Function: JFire --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : jf.b=JFire(joy#) This command tests the fire button status of the joystick joy#, where joy# is between 1 and 4. You should note that, as with all the joystick commmands, joy#=1 refers to the Amiga's joystick port, joy#=2 refers to the mouse port, and joy#=3 or joy#=4 refer to the four player adapter ports. This command returns 0 for fire button not pressed or -1 for pressed Function: JHoriz --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : jh.b=JHoriz(joy#) This command is used to test the horizontal direction of the selected joystick. It returns: 0: No horizontal direction -1: Joystick left 1: Joystick right Function: JVert --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : jv.b=JVert(joy#) This command is used to test the vertical direction of the selected joystick. It returns: 0: No vertical direction -1: Joystick up 1: Joystick down Function: AllFire --------------------------------------------------------------------------- Modes : Amiga/Blitz Syntax : af.b=AllFire [(bit_pattern)] This command is used to test the fire button status of all four joysticks. It returns a byte with the first four bits giving the joystick status, false=fire button not pressed, true=fire button pressed. The following bits belong to joysticks: bit 0: joystick 1 (joystick port) bit 1: joystick 2 (mouse port) bit 2: joystick 3 (four player adaptor) bit 3: joystick 4 (four player adaptor) The optional bit pattern can be used to restrict the testing of the fire buttons. If a bit in the pattern is clear (false) then the joystick it belongs to will not have its fire button tested, e.g. AllFire (%0011) will test joysticks 1 and 2 and return the result. It will return false for joysticks 3 and 4. Library: neilsciatrackerlib #56 -------------------------------------------------------------------------- Author: Neil O'Rourke, 6 Victoria St, TAMWORTH, NSW 2340, AUSTRALIA Overview: Many thanks to Neil, from what I have seen on the net there are already many BlitzUsers using this library to great success. I'm trying to fit the example code on the disk as I type... QUICK USAGE AUTHOR'S DOC The CIA Tracker commands: BUILDNOTETABLE GETSONGPOSITION CHECKTRACKEREVENT GETTRACKEREVENT CHECKTRACKERMODULEID GETTRACKERINSTRUMENT FREETRACKERMODULE GETTRACKERLOCATION GETPATTERNPOSITION GETTRACKERNAME GETSAMPLELENGTH GETTRACKERNOTE GETSAMPLELOCATION GETTRACKERNOTENUMBER GETSAMPLENAME GETTRACKERSIZE GETSONGLENGTH GETTRACKERVOLUME INITTRACKER SETTRACKERMODULE LOADTRACKERMODULE SETTRACKERTEMPO OLDGETTRACKERNOTENUMBER STARTTRACKER PAUSETRACKER STARTTRACKERPATPOS PLAYTRACKERSAMPLE STOPTRACKER RESTARTTRACKER WAITTRACKEREVENT SETDMAWAIT SETSONGPATTERNPOSITION SETTRACKERMASK Notes: ~~~~~~ Quite a number of these commands extract their data from the playroutine in real time; that is, around fifty times a second (depending upon the tempo). Therefore, the value your program receives could well be very different from what is actually happening in the song. Disclaimer: ~~~~~~~~~~~ By installing this software on your system, you are agreeing that I have no liability as to the outcome of such use. If, for example, you use a command as documented and a floppy disk is ejected from your disk drive with such force that it severs your head from your neck, tough. Next time, duck. Author's Documentation: CIATracker.lib Documentation Neil O'Rourke Version 1.6 (24/6/94) Introduction ~~~~~~~~~~~~ The standard soundtracker replay routines supplied with Blitz Basic 2 have many faults, which this library attempts to overcome. Some of the features are: - Plays all ST/NT/PT songs that utilise either the VBLANK timing or the more recent CIA based timings - Plays back correctly on 50/60Hz systems, running either PAL or NTSC - Contains more specialised functions for advanced programmers - Enables the programmer to syncronise graphics with their music Credits: ~~~~~~~~ Original ProTracker playroutine by Amiga Freelancers, converted and enhanced for Blitz by Neil O'Rourke. Naggings from Roy, Jeff and Richard. The 1.6 upgrade ~~~~~~~~~~~~~~~ This is a maintenance upgrade, with some subtle (and not so subtle) bugs fixed or noted. LoadTrackerModule no longer crashes the machine if the name was invalid. SetTrackerMask has been removed for the moment (this was causing the TrackerEvent system to foul up) WaitTrackerEvent has a nasty tendancy to lock the machine up. Don't call this command, use While NOT CheckTrackerEvent:Wend to wait for an event if you must. WaitTrackerEvent currently sits on the VBLANK interrupt, however I think the problem is due to the sheer bulk of ciaTrackerLib getting in the way of checking. I think. GetTrackerNoteNumber was found to be chewing up CPU time, and has been replaced by a new version that chews up 2K of ram extra. I've found that if you have run errors enabled to bring up the requester, your module won't start sometimes. Don't know what to do about this, as I don't know what causes it. Quick Usage: ~~~~~~~~~~~~ First you must set the DMAWait time with the SetDMAWait command. Then, enable all the channels with SetTrackerMask. Load the module you want with the LoadTrackerModule command, and then either StartTrackerModule it, or InitTracker/RestartTracker later on. Function: LoadTrackerModule -------------------------------------------------------------------------- Syntax : success=LoadTrackerModule(TrackerModule#,FileName$) Description: Loads the named module into chip ram, ready for playing. This command can only be called in Amiga mode. success is a boolean return code (true). If the load fails for any reason, success returns the AmigaDOS error code. Note that there is an implicit call to FreeTrackerModule for whatever module you are trying to load. However, if you want to load another module, don't try to load it on top of the existing one that is playing. Use another TrackerModule# (you have from 0 to 8). The results are unpredictable, and range from nothing to a system crash. We can't call StopTracker, because this will stop everything. Function: StartTracker -------------------------------------------------------------------------- Syntax : success=StartTracker(TrackerModule#) Description: Starts to play the requested module, stopping any modules already playing, or restarts the current module, and returns true. Returns false if the module couldn't be started for some reason (like it isn't loaded). Statement: StopTracker -------------------------------------------------------------------------- Description: Stops the current module Statement: SetDMAWait -------------------------------------------------------------------------- Syntax : SetDMAWait value Description: This sets the DMA Wait for your machine. On a standard 7.14MHz 68000 based machine, the value is the default (300). However, faster machines can cause the replay routine to skip notes. On a 25MHz 68030 machine, the suggested value is 900. Set this as low as possible so that you still hear all the notes. A future upgrade *may* do this automatically, but I have no intention of implementing it at this stage, as I don't know what DMAWait to set for different speed processors and version motherboards. DMA wait is important. Technically, when the replay routine loads the chip registers with the information about the current note (location, volume, pitch), a delay is needed to ensure that the chips actually get the data, which happens on the next DMA slot. Since the CPU can be clocked independantly of the motherboard, we can't just delay by a set amount. How this problem has been solved is a busy wait that simply loops around the number of times as specified by the DMAWait value. A low value therefore lessens the load on the CPU but increases the chances of missing notes while playing a song. Too high a value can bog the CPU down, and slow the song down as interrupts are missed. Statement: FreeTrackerModule -------------------------------------------------------------------------- Syntax : FreeTrackerModule TrackerModule# Description: This frees a module loaded with LoadTrackerModule. You cannot free a module that has been set up with SetTrackerModule (see below), but there is nothing to stop you trying. Statement: SetTrackerModule -------------------------------------------------------------------------- Syntax : SetTrackerModule TrackerModule#,ModuleAddress Description: This sets an arbitary area of memory as a tracker module, useful if you have BLoaded a file and want to hear if it is a module. Caution: a non-module may crash the Amiga. Functions: GetTrackerSize & GetTrackerLocation -------------------------------------------------------------------------- Syntax : trackerlength=GetTrackerSize(TrackerModule#) GetTrackerLocation (TrackerModule#) Description: Both these functions return information about the module that has been loaded with LoadTrackerModule. There should be no need to use this information, and these commands are only included because they served a purpose in debugging a long time ago, and to remove them would cause problems with the Blitz tokens Function: GetTrackerEvent -------------------------------------------------------------------------- Syntax : trackerevent=GetTrackerEvent Description: This command is a customised extension to the ProTracker replay routine. A "TrackerEvent" occurs when the replay routine comes across a $8xx command. This command is not defined in the command list, and many demos (eg Jesus on E's) use it to trigger effects. This command gets the most recent TrackerEvent, so any program looking at this will have to compare the current value to the value that triggered the current effect. Function: CheckTrackerEvent -------------------------------------------------------------------------- Syntax : success=CheckTrackerEvent Description: This routine checks to see if a TrackerEvent has occured since the last time the routine was called, and returns True if it has. Use GetTrackerEvent to determine what data the $8xx command had. Statement: WaitTrackerEvent -------------------------------------------------------------------------- ** V1.6: DO NOT USE THIS COMMAND! ** Function: CheckTrackerModuleID -------------------------------------------------------------------------- Syntax : success=CheckTrackerModuleID(TrackerModule#) Description: This checks the module for the standard Pro/Noise/SoundTracker ID string "M.K." (or "M!K!" in the case of a 100 pattern PT module), and returns True if one of them is found. This means that you can safely call StartTracker. Note that there is no 100% guarenteed way of determining what is a module and what isn't. Bit Arts, for example, remove the M.K. identifier to make it harder to rip modules, so if you're writing a module ripping program, you have to take this result with a grain of salt. Function: GetTrackerVolume -------------------------------------------------------------------------- Syntax : volume=GetTrackerVolume(TrackerChannel#) Description: Returns the last volume set by a $Cxx command for the named channel, which are numbered from 0 to 3. This is not the "real" volume of the sample that is currently playing. Function: GetTrackerNote -------------------------------------------------------------------------- Syntax : note=GetTrackerNote(TrackerChannel#) Description: Returns the note that the play routine has just played in the named channel. This command is really only useful for graphic bars or simple syncronisation of graphics to the music, but for that purpose the TrackerEvent commands are far more flexable. Note that the value returned is the period of the note. You have to look up the note in a period table to find out what was actually being played. Statement: SetTrackerTempo -------------------------------------------------------------------------- Syntax : SetTrackerTempo Tempo Description: Sets the tempo of the current song. Note that a tempo command ($Fxx) will override any value set by this command. This command is really a stub to the actual $Fxx command in the playroutine, and has all the features associated with it. Check your tracker docs for more details. Function: GetTrackerInstrument -------------------------------------------------------------------------- Syntax : instrument=GetTrackerInstrument(TrackerChannel#) Description: Gets the instrument that is playing in the channel. Function: GetPatternPosition -------------------------------------------------------------------------- Syntax : PatPos=GetPatternPosition Description: This returns the current position in the current pattern. Function: GetSongPosition -------------------------------------------------------------------------- Syntax : SongPos=GetSongPosition Description: This returns the current pattern that is playing in the song Statement: SetSongPatternPosition -------------------------------------------------------------------------- Syntax : SetSongPatternPosition Pattern#,Position# Description: This command sets what pattern to play, and from what position. Use this while a song is playing to jump to another pattern (eg. a game over music). Call StartTrackerPatPos() to start a module from scratch. Function: GetSongLength -------------------------------------------------------------------------- Syntax : NumPatterns=GetSongLength Description: Returns the number of patterns in the current module. Useful for displays like in IntuiTracker, where the title bar of the window gives a display that can be done like: NPrint GetSongLength,":",GetSongPosition Statement: SetTrackerMask -------------------------------------------------------------------------- Syntax : SetTrackerMask Mask ** REMOVED IN V1.6 ** Function: OldGetTrackerNoteNumber -------------------------------------------------------------------------- Syntax : notenumber=OldGetTrackerNoteNumber(Channel#) Description: This returns the number of the note played on the specified channel, with C-1 being note 1. Of use really in creating "equalizer bars". V1.6: This command has turned out to be a CPU-hog! The new implementation will consume a lot of memory but will be much faster. When you load your old programs, GetTracker... will be replaced by OldGetTracker..., so your code will continue to work. Function: StartTrackerPatPos -------------------------------------------------------------------------- Syntax : ret.l=StartTrackerPatPos(TrackerModule#,Pattern#,Position#) This starts the named module at the requested pattern and position. In all other respects it is the same as StartTracker. Statements: PauseTracker & RestartTracker -------------------------------------------------------------------------- Description: These commands allow you to stop a tracker module are restart it at a later time. Statement: PlayTrackerSample -------------------------------------------------------------------------- Syntax : PlayTrackerSample Sample#,Period,Volume,Channel Description: Plays a sample through the channel. The module must not be running. Statement: InitTracker -------------------------------------------------------------------------- Syntax : success=InitTracker(TrackerModule#) Description: Identical to StartTracker, except that the module doesn't start, but is initialised. Of use with the commands that use the current tracker module. Use ReStartTracker to start playing. Function: GetSampleLocation -------------------------------------------------------------------------- Syntax : location=GetSampleLocation(Sample#) Description: Returns the address in memory of the named sample in the current module. Function: GetSampleLength -------------------------------------------------------------------------- Syntax : length=GetSampleLength(Sample#) Description: Returns the length in words of the named sample in the current module. Multiply by two to get the byte length. Function: GetSampleName -------------------------------------------------------------------------- Syntax : name$=GetSampleName(Sample#) Description: Returns the name of the sample in name$. Function: GetTrackerName -------------------------------------------------------------------------- Syntax : name$=GetTrackerName(TrackerModule#) Description: Returns the name of the module in name$ Statement: BuildNoteTable -------------------------------------------------------------------------- Description: This command builds a note table for use with GetTrackerNoteNumber. It consumes 2K of memory for the look-up table. Function: GetTrackerNoteNumber -------------------------------------------------------------------------- Syntax : notenumber=GetTrackerNoteNumber(Channel#) Description: This returns the number of the note played on the specified channel, with C-1 being note 1. Of use really in creating "equalizer bars". For speed purposes, no error checking (like, has the note table been built?) is done. There's not much to tell about the Elmore library, it's GREAT! Library name: ELMORELIB Written by: Richard T. Elmore Copyright: 1994 HeadSoft Software Library number: 111 HARDWARE PROGRAMMING MATH/NUMERIC FUNCTIONS ARRAY FUNCTIONS INTUITION PROGRAMMING STRING HANDLING LIBRARY PROGRAMMING ELMORE HARDWARE LIBRARY -------------------------------------------------------------------------- CLICKMOUSE FORCENTSC FORCEPAL FREQ QUIET RESETTIMER VWAITPOS =CHECKAGA =CHIPFREE =DEPTH =FASTFREE =JOYC =LARGESTFREE =PEEKTO$ =TICKS ELMORE MATH LIBRARY -------------------------------------------------------------------------- RRANDOMIZE =AVG =AVG.L =AVG.Q =LARGEST =LARGEST.L =LARGEST.Q =RRND =SMALLEST =SMALLEST.L =SMALLEST.Q =XOR INTUITION PROGRAMMING -------------------------------------------------------------------------- REQUEST SHOWREQUESTORS WAITFOR =ACTIVESCREEN =ACTIVEWINDOW =SCREENHEIGHT =SCREENWIDTH STRING HANDELING -------------------------------------------------------------------------- =BIN# =CHARCOUNT =CHECKSUM =CIPHER$ =HEX# =NULL =REPEATS =SEARCHBEGIN =SEARCHBEGIN =SPACE$ LIBRARY PROGRAMMING -------------------------------------------------------------------------- These functions will return the base address of their respective libraries, for advanced system programming. Note that register A6 will also be loaded with this address, to make programming a bit easier for assembly routines. COMMODITIEBASE DISKFONTBASE DOSBASE FFPBASE GRAPHICSBASE ICONBASE INTUITIONBASE REXXSYSBASE Statement: QUIET --------------------------------------------------------------------------- Syntax: Quiet ChannelMask Modes: Amiga or Blitz This command will silence the sound channels specified by ChannelMask. See the description for "Envelope" for more information on channelmasks. Statement: FREQ --------------------------------------------------------------------------- Syntax: Freq Channelmask,period Modes: Amiga or Blitz This command allows you to change the period, or pitch, of the currently playing sound effect. Note that the lower the period, the higher the frequency; Thus, a period of 100 would be very high-pitched, whereas a period of 30000 would be low-pitched. Function: TICKS --------------------------------------------------------------------------- Syntax: Ticks Modes: Amiga or Blitz This function returns the number of "ticks" since the Amiga was switched on, or since the last "RESETTIMER" command. The unit of measurement is 1/60 of a second for NTSC machines, and 1/50 of a second for PAL machines. See Also: RESETTIMER END OF PART ONE